home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2005 October / PCWOCT05.iso / Software / FromTheMag / XAMPP 1.4.14 / xampp-win32-1.4.14-installer.exe / xampp / mysql / scripts / fill_help_tables next >
Text File  |  2005-04-01  |  16KB  |  604 lines
  1. #!/usr/bin/perl
  2. #
  3. # Copyright (C) 2003 MySQL AB
  4. # For a more info consult the file COPYRIGHT distributed with this file.
  5. #
  6. # This script generates the SQL statements required by mysql_install_db to
  7. # fill up the tables for the server-side online function help, which can be
  8. # invoked with "help <function>" from the MySQL client.
  9. #
  10. # Usage:
  11. #   fill_help_tables OPTIONS  < manual.texi > fill_help_tables.sql
  12. #  
  13. #  --help           display this helpscreen and exit
  14. #  --verbose        print information about help completeness to STDERR
  15. #  --lexems=path    path to file with lexems. it is used with verbose option.
  16. #                       default value is ../sql/lex.h
  17. # Examples:
  18. #  ./fill_help_tables --help
  19. #  ./fill_help_tables --verbose < manual.texi > fill_help_tables.sql
  20. #  ./fill_help_tables < manual.texi > fill_help_tables.sql
  21. # 
  22. # Please note, that you first need to update Docs/manual.texi with the
  23. # manual file from the separate "mysqldoc" BitKeeper-Tree! The manual.texi
  24. # included in the source tree is just an empty stub file - the full manual
  25. # is now maintained in a separate tree.
  26. #
  27. # extra tags in manual.texi:
  28. #
  29. #    @c help_category <category_name>[@<parent_category_name>]
  30. #
  31. #    @c description_for_help_topic <topic_name>  <keyword1> <keyword2>
  32. #        ....
  33. #    @c end_description_for_help_topic
  34. #
  35. #    @c example_for_help_topic <topic_name>
  36. #    @example
  37. #        ....
  38. #    @end example
  39. #
  40. #
  41. # Original version by Victor Vagin <vva@mysql.com>
  42. #
  43.  
  44. use strict;
  45. use Getopt::Long;
  46.  
  47. my $insert_portion_size= 15;
  48. my $error_prefix= "---- help parsing errors :";
  49.  
  50. my $path_to_lex_file= "../sql/lex.h";
  51. my $verbose_option= 0;
  52. my $help_option= 0;
  53.  
  54. my $cur_line= 0;
  55. my $count_errors= 0;
  56.  
  57. GetOptions(
  58.   "help",\$help_option,
  59.   "verbose",\$verbose_option,
  60.   "lexems=s",\$path_to_lex_file
  61. );
  62.  
  63. if ($help_option ne 0)
  64. {
  65.   print <<_HELP;
  66.  
  67. This script generates the SQL statements required by mysql_install_db to
  68. fill up the tables for the server-side online function help, which can be
  69. invoked with "help <function>" from the MySQL client.
  70.  
  71. Usage:
  72.   fill_help_tables OPTIONS  < manual.texi > fill_help_tables.sql
  73.   
  74.   --help           display this helpscreen and exit
  75.   --verbose        print information about help completeness to STDERR
  76.   --lexems=path    path to file with lexems. it is used with verbose option.
  77.                        default value is ../sql/lex.h
  78.  
  79. Examples:
  80.   ./fill_help_tables --help
  81.   ./fill_help_tables --verbose < manual.texi > fill_help_tables.sql
  82.   ./fill_help_tables < manual.texi > fill_help_tables.sql
  83.     
  84. _HELP
  85.   exit;
  86. }
  87.  
  88. my $current_category= "";
  89. my $current_parent_category= "";
  90. my $next_example_for_topic= "";
  91.  
  92. my %topics; 
  93. my %categories;
  94. my %keywords;
  95.  
  96. $categories{Contents}->{__parent_category__}= "";
  97.  
  98. sub print_error
  99. {
  100.   my ($text)= @_;
  101.   if ($count_errors==0)
  102.   {
  103.     print STDERR "$error_prefix\n";
  104.   }
  105.   print STDERR "line $cur_line : $text";
  106.   $count_errors++;
  107. }
  108.  
  109. sub add_topic_to_category
  110. {
  111.   my ($topic_name)= @_;
  112.  
  113.   $categories{$current_category}->{$topic_name}= $topics{$topic_name};
  114.   my $category= $categories{$current_category};
  115.   $category->{__name__}= $current_category;
  116.     
  117.   if (exists($category->{__parent_category__}))
  118.   {
  119.     my $old_parent= $category->{__parent_category__};
  120.     if ($old_parent ne $current_parent_category)
  121.     {
  122.       print_error "wrong parent for $current_category\n";
  123.     }
  124.   }
  125.  
  126.   if ($current_parent_category ne "")
  127.   {
  128.     $category->{__parent_category__}= $current_parent_category;
  129.   }
  130.     
  131.   if (exists($topics{$topic_name}->{category}))
  132.   {
  133.     my $old_category= $topics{$topic_name}->{category};
  134.     if ($old_category ne $category)
  135.     {
  136.       print_error "wrong category for $topic_name (first one's \"$old_category->{__name__}\" second one's \"$current_category\")\n";
  137.     }
  138.   }
  139.     
  140.   $topics{$topic_name}->{category}= $category;    
  141. }
  142.  
  143. sub add_example
  144. {
  145.   my ($topic_name,$example)= @_;
  146.     
  147.   $topic_name=~ tr/a-z/A-Z/;
  148.  
  149.   if (exists($topics{$topic_name}->{example}))
  150.   {
  151.     print_error "double example for $topic_name\n";
  152.   }
  153.     
  154.   $topics{$topic_name}->{example}= $example;    
  155.   add_topic_to_category($topic_name);
  156. }
  157.  
  158. sub add_description
  159. {
  160.   my ($topic_name,$description)= @_;
  161.     
  162.   $topic_name=~ tr/a-z/A-Z/;
  163.     
  164.   if (exists($topics{$topic_name}->{description}))
  165.   {
  166.     print_error "double description for $topic_name\n";
  167.   }
  168.   $topics{$topic_name}->{description}= $description;
  169.   add_topic_to_category($topic_name);
  170. }
  171.  
  172. sub add_keyword
  173. {
  174.   my ($topic_name,$keyword)= @_;
  175.     
  176.   $topic_name=~ tr/a-z/A-Z/;
  177.   $keyword=~ tr/a-z/A-Z/; 
  178.     
  179.   push(@{$topics{$topic_name}->{keywords}},$keyword);
  180.   if (exists($keywords{$keyword}->{$topic_name}))
  181.   {
  182.     print_error "double keyword $keyword for $topic_name\n";
  183.   }
  184.   $keywords{$keyword}->{$topic_name}= $topics{$topic_name};
  185. }
  186.  
  187. sub prepare_name
  188. {
  189.   my ($a)= @_;
  190.     
  191.   $a =~ s/(\@itemize \@bullet)/  /g;
  192.   $a =~ s/(\@end itemize)/  /g;
  193.   $a =~ s/(\@end multitable)/  /g;
  194.   $a =~ s/(\@end table)/  /g;
  195.   $a =~ s/(\@cindex(.*?)\n)/  /g;
  196.   $a =~ s/(\@multitable \@columnfractions(.*?)\n)/  /g;
  197.   $a =~ s/(\@node(.*?)\n)/  /g;
  198.   $a =~ s/(\@tab)/\t/g;
  199.   $a =~ s/\@item/  /g;
  200.   $a =~ s/\@minus\{\}/-/g;
  201.   $a =~ s/\@dots\{\}/.../g;
  202.   $a =~ s/\@var\{((.|\n)+?)\}/$1/go;
  203.   $a =~ s/\@command\{((.|\n)+?)\}/$1/go;
  204.   $a =~ s/\@code\{((.|\n)+?)\}/$1/go;
  205.   $a =~ s/\@strong\{(.+?)\}/$1/go;
  206.   $a =~ s/\@samp\{(.+?)\}/'$1'/go;
  207.   $a =~ s/\@emph\{((.|\n)+?)\}/\/$1\//go;
  208.   $a =~ s/\@xref\{((.|\n)+?)\}/See also : [$1]/go;
  209.   $a =~ s/\@ref\{((.|\n)+?)\}/[$1]/go;
  210.   $a =~ s/\'/\'\'/g;
  211.   $a =~ s/\\/\\\\/g;
  212.   $a =~ s/\`/\`\`/g;
  213.  
  214.   $a =~ s/\@table \@code/  /g;
  215.   $a =~ s/\(\)//g;
  216.   $a =~ s/\"/\\\"/g;
  217.  
  218.   $a =~ s/((\w|\s)+)\(([\+-=><\/%*!<>\s]+)\)/$3/gxs;
  219.   $a =~ s/([\+-=><\/%*!<>\s]+)\(((\w|\s)+)\)/$1/gxs;
  220.   $a =~ s/((\w|\s)+)\((.+)\)/$1/gxs;
  221.   
  222.   $a =~ s/((\s)+)$//g;
  223.                                                     
  224.   return $a;
  225. }
  226.  
  227. sub prepare_description
  228. {
  229.   my ($a)= @_;
  230.  
  231.   $a =~ s/(\@itemize \@bullet\n)//g;
  232.   $a =~ s/(\@c help_keyword (.*?)\n)//g;
  233.   $a =~ s/(\@end itemize\n)//g;
  234.   $a =~ s/(\@end example\n)//g;
  235.   $a =~ s/(\@example\n)//g;
  236.   $a =~ s/(\@{)/{/g;
  237.   $a =~ s/(\@})/}/g;
  238.   $a =~ s/(\@end multitable)/  /g;
  239.   $a =~ s/(\@end table)/  /g;
  240.   $a =~ s/(\@cindex(.*?)\n)//g;
  241.   $a =~ s/(\@findex(.*?)\n)//g;
  242.   $a =~ s/(\@table(.*?)\n)//g;
  243.   $a =~ s/(\@multitable \@columnfractions(.*?)\n)/  /g;
  244.   $a =~ s/(\@node(.*?)\n)/  /g;
  245.   $a =~ s/(\@tab)/\t/g;
  246.   $a =~ s/\@itemx/  /g;
  247.   $a =~ s/(\@item\n(\s*?))(\S)/ --- $3/g;
  248.   $a =~ s/(\@item)/  /g;
  249.   $a =~ s/(\@tindex\s(.*?)\n)//g;
  250.   $a =~ s/(\@c\s(.*?)\n)//g;
  251.   $a =~ s/\@minus\{\}/-/g;
  252.   $a =~ s/\@dots\{\}/.../g;
  253.   $a =~ s/\@var\{((.|\n)+?)\}/$1/go;
  254.   $a =~ s/\@command\{((.|\n)+?)\}/$1/go;
  255.   $a =~ s/\@code\{((.|\n)+?)\}/$1/go;
  256.   $a =~ s/\@strong\{(.+?)\}/$1/go;
  257.   $a =~ s/\@samp\{(.+?)\}/'$1'/go;
  258.   $a =~ s/\@emph\{((.|\n)+?)\}/\/$1\//go;
  259.   $a =~ s/\@xref\{((.|\n)+?)\}/See also : [$1]/go;
  260.   $a =~ s/\@ref\{((.|\n)+?)\}/[$1]/go;
  261.   $a =~ s/\@w\{((.|\n)+?)\}/$1/go;
  262.   $a =~ s/\@strong\{((.|\n)+?)\}/\n!!!!\n$1\n!!!!\n/go;
  263.   $a =~ s/\@file\{((.|\n)+?)\}/\*$1/go;
  264.   $a =~ s/\\/\\\\/g;
  265.   $a =~ s/\n\n$/\n/g;
  266.   $a =~ s/\n\n$/\n/g;
  267.   $a =~ s/\n\n$/\n/g;
  268.   $a =~ s/\n\n$/\n/g;
  269.   $a =~ s/\n\n$/\n/g;
  270.   $a =~ s/\n/\\n/g;
  271.   $a =~ s/\"/\\\"/g;
  272.  
  273.   $a =~ s/\@table \@code/  /g;
  274.  
  275.   return $a;
  276. }
  277.  
  278. sub prepare_example
  279. {
  280.   my ($a)= @_;
  281.  
  282.   $a =~ s/(^\@c for_help_topic(.*?)\n)//g;
  283.  
  284.   $a =~ s/\@var\{((.|\n)+?)\}/$1/go;
  285.   $a =~ s/\@dots\{\}/.../g;
  286.   $a =~ s/\\/\\\\/g;
  287.   $a =~ s/(\@{)/{/g;
  288.   $a =~ s/(\@})/}/g;
  289.   $a =~ s/(\@\@)/\@/g;
  290.   $a =~ s/(\n*?)$//g;
  291.   $a =~ s/\n/\\n/g;
  292.   $a =~ s/\"/\\\"/g;
  293.     
  294.   return $a;
  295. }
  296.  
  297. sub parse_example
  298. {
  299.   return if (!($_=~/\@example/));
  300.   return if ($next_example_for_topic eq "");
  301.     
  302.   my $topic_name= $next_example_for_topic;
  303.   $next_example_for_topic= "";
  304.   my $text= "";
  305.     
  306.   while (<>)
  307.   {
  308.     $cur_line++;
  309.     last if ($_=~/\@end example/);
  310.     $text .= $_;
  311.   }
  312.     
  313.   $text= prepare_example($text);
  314.   $topic_name= prepare_name($topic_name);
  315.   add_example($topic_name,$text) if ($topic_name ne "");
  316. }
  317.  
  318. sub parse_example_for_topic
  319. {
  320.   my ($for_topic)= m|\@c example_for_help_topic (.+?)$|;
  321.   return if ($for_topic eq "");
  322.     
  323.   $next_example_for_topic= $for_topic;    
  324. }
  325.  
  326. sub parse_description
  327. {
  328.   my ($topic_description)= m|\@c description_for_help_topic (.+?)$|;
  329.   return if ($topic_description eq "");
  330.     
  331.   my ($topic_name,$topic_keywords)= split(/  /,$topic_description);
  332.     
  333.   if ($topic_name eq "" || $topic_keywords eq "")
  334.   {
  335.     $topic_name= $topic_description;
  336.   }
  337.   else
  338.   {
  339.     my $keyword;
  340.     foreach $keyword (split(/ /,$topic_keywords))
  341.     {
  342.       add_keyword($topic_name,$keyword) if ($keyword ne "");
  343.     }
  344.   }
  345.     
  346.   my $text= "";
  347.     
  348.   while (<>)
  349.   {
  350.     $cur_line++;
  351.     last if ($_=~/\@c end_description_for_help_topic/);
  352.     $text .= $_;
  353.   }
  354.     
  355.   $text= prepare_description($text);
  356.   $topic_name= prepare_name($topic_name);
  357.   add_description($topic_name,$text);
  358. }
  359.  
  360. sub parse_category
  361. {
  362.   my ($c_name,$pc_name)= m|\@c help_category (.+?)\@(.+?)$|;
  363.  
  364.   if ($pc_name ne "")
  365.   {
  366.     $current_category= prepare_name($c_name);
  367.     $current_parent_category= prepare_name($pc_name);
  368.   }
  369.   else
  370.   {
  371.     my ($c_name)=m|\@c help_category (.+?)$|;
  372.     return if ($c_name eq "");
  373.  
  374.     $current_category= prepare_name($c_name);
  375.     $current_parent_category= "Contents"
  376.   }
  377. }
  378.  
  379. # parse manual:
  380.  
  381. while (<>)
  382. {
  383.   parse_example_for_topic ();
  384.   parse_example           ();
  385.   parse_description       ();    
  386.   parse_category          ();
  387.   $cur_line++;
  388. }
  389.  
  390. # test results of parsing:
  391.  
  392. sub print_bad_names
  393. {
  394.   my($names,$prompt)= @_;
  395.   if (scalar(@{$names}))
  396.   {
  397.     print STDERR "\n-------------- $prompt : \n\n";
  398.     my $name;
  399.     foreach $name (@{$names})
  400.     {
  401.       print STDERR "$name\n";
  402.     }
  403.     print STDERR "\n";
  404.   }
  405. }
  406.  
  407. sub print_verbose_errors
  408. {
  409.   my($name_of_log_file)= @_;
  410.  
  411.   my @without_help;
  412.   my @description_with_at;
  413.   my @example_with_at;
  414.   my @without_description;
  415.   my @without_example;
  416.     
  417.   print STDERR "\n-------------- parameters of help completeness : \n\n";
  418.     
  419.   my $count_lex= 0;
  420.   if (!open (TLEX,"<$path_to_lex_file"))
  421.   {
  422.     print STDERR "Error opening lex file \"$path_to_lex_file\" $!\n";
  423.   }
  424.   else
  425.   {    
  426.     for (<TLEX>)
  427.     {
  428.       my ($a,$lex,$b)=m|(.+?)\"(.+?)\"(.+?)$|;
  429.       next if ($lex eq "");
  430.       $count_lex++;
  431.       next if (exists($topics{$lex}) || exists($keywords{$lex}));
  432.       push(@without_help,$lex);
  433.     }
  434.     close(TLEX);
  435.     print STDERR "number of lexems in \"$path_to_lex_file\" - $count_lex\n";
  436.   }
  437.     
  438.   my $name;
  439.   my @topic_names= keys(%topics);
  440.   foreach $name (@topic_names)
  441.   {
  442.     my $topic= $topics{$name};
  443.     push(@description_with_at,$name) if ($topic->{description}=~/\@/);
  444.     push(@example_with_at,$name) if ($topic->{example}=~/\@/);
  445.     push(@without_description,$name) if (!exists($topic->{description}));
  446.     push(@without_example,$name) if (!exists($topic->{example}));
  447.   }
  448.     
  449.   my $count_categories= scalar(keys(%categories));
  450.   print STDERR "number of help categories          - ",$count_categories,"\n";
  451.   my $count_topics= scalar(@topic_names);
  452.   print STDERR "number of help topics              - ",$count_topics,"\n";
  453.   my $count_keywords= scalar(keys(%keywords));
  454.   print STDERR "number of help keywords            - ",$count_keywords,"\n";
  455.     
  456.   my $count_without_help= scalar(@without_help);
  457.   my $percent_without_help= $count_lex ?
  458.                             int (($count_without_help/$count_lex)*100) :
  459.                             "100";
  460.   print_bad_names(\@without_help,"lexems without help (".
  461.                             $count_without_help." ~ ".
  462.                             $percent_without_help."%)");
  463.   print_bad_names(\@description_with_at,
  464.           " topics below have symbol \'@\' in their descriptions.\n".
  465.           "it's probably the litter from 'texi' tags (script needs fixing)");
  466.   print_bad_names(\@example_with_at,
  467.           " topics below have symbol \'@\' in their examples.\n".
  468.           "it's probably the litter from 'texi' tags (script needs fixing)");
  469.   print_bad_names(\@without_description,"topics without description");
  470.     
  471.   my $count_without_example= scalar(@without_example);
  472.   my $percent_without_example= $count_topics ?
  473.                             int (($count_without_example/$count_topics)*100) :
  474.                             "100";
  475.   print_bad_names(\@without_example,"topics without example (".
  476.                             $count_without_example." ~ ".
  477.                             $percent_without_example."%)");
  478. }
  479.  
  480. print_verbose_errors if ($verbose_option ne 0);
  481.  
  482. # output result 
  483.  
  484. sub print_insert_header
  485. {
  486.   my($count,$header)= @_;
  487.     
  488.   if ($count % $insert_portion_size ne 0) {
  489.     print ",";
  490.   } else {
  491.     print ";\n" if ($count ne 0);
  492.     print "$header";
  493.   }
  494. }
  495.  
  496. print <<EOF;
  497. -- Copyright (C) 2000-2005 MySQL AB
  498. -- 
  499. -- This program is free software; you can redistribute it and/or modify
  500. -- it under the terms of the GNU General Public License as published by
  501. -- the Free Software Foundation; either version 2 of the License, or
  502. -- (at your option) any later version.
  503. -- 
  504. -- This program is distributed in the hope that it will be useful,
  505. -- but WITHOUT ANY WARRANTY; without even the implied warranty of
  506. -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  507. -- GNU General Public License for more details.
  508. -- 
  509. -- You should have received a copy of the GNU General Public License
  510. -- along with this program; if not, write to the Free Software
  511. -- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  512.  
  513. EOF
  514. print "delete from help_topic;\n";
  515. print "delete from help_category;\n";
  516. print "delete from help_keyword;\n";
  517. print "delete from help_relation;\n\n";
  518.  
  519. my @category_names= keys(%categories);
  520. if (scalar(@category_names))
  521. {
  522.   my $cat_name;
  523.   my $count= 0;
  524.   foreach $cat_name (@category_names)
  525.   {
  526.     $categories{$cat_name}->{__id__}= $count;
  527.     $count++;
  528.   }
  529.  
  530.   my $header= "insert into help_category ".
  531.             "(help_category_id,name,parent_category_id) values ";
  532.   $count= 0;
  533.   foreach $cat_name (@category_names)
  534.   {
  535.     print_insert_header($count,$header);
  536.     my $parent_cat_name= $categories{$cat_name}->{__parent_category__};
  537.     my $parent_cat_id= $parent_cat_name eq "" 
  538.         ? "-1" : $categories{$parent_cat_name}->{__id__};
  539.     print "($count,\"$cat_name\",$parent_cat_id)";
  540.     $count++;
  541.   }
  542.   printf ";\n\n";
  543. }
  544.  
  545. my @topic_names= keys(%topics);
  546. if (scalar(@topic_names))
  547. {
  548.   my $header= "insert into help_topic ".
  549.       "(help_topic_id,help_category_id,name,description,example) values ";
  550.   my $topic_name;
  551.   my $count= 0;
  552.   foreach $topic_name (@topic_names)
  553.   {
  554.     print_insert_header($count,$header);
  555.     my $topic= $topics{$topic_name};
  556.     print "($count,";
  557.     print "$topic->{category}->{__id__},";
  558.     print "\"$topic_name\",";
  559.     print "\"$topic->{description}\",";
  560.     print "\"$topic->{example}\")";
  561.     $topics{$topic_name}->{__id__}= $count;
  562.     $count++;
  563.   }
  564.   printf ";\n\n";
  565. }
  566.  
  567. my @keywords_names= keys(%keywords);
  568. if (scalar(@keywords_names))
  569. {
  570.   my $header= "insert into help_keyword (help_keyword_id,name) values ";
  571.   my $keyword_name;
  572.   my $count= 0;
  573.   foreach $keyword_name (@keywords_names)
  574.   {
  575.     print_insert_header($count,$header);
  576.     print "($count,\"$keyword_name\")";
  577.     $count++;
  578.   }
  579.   printf ";\n\n";
  580.     
  581.   $header= "insert into help_relation ".
  582.     "(help_topic_id,help_keyword_id) values ";
  583.   $count= 0;
  584.   my $count_keyword= 0;
  585.   foreach $keyword_name (@keywords_names)
  586.   {
  587.     my $topic_name;
  588.     foreach $topic_name (keys(%{$keywords{$keyword_name}}))
  589.     {
  590.       print_insert_header($count,$header);
  591.       print "($topics{$topic_name}->{__id__},$count_keyword)";
  592.       $count++;
  593.     }
  594.     $count_keyword++;
  595.   }
  596.   printf ";\n\n";
  597. }
  598.  
  599. if ($count_errors)
  600. {
  601.   print STDERR "$count_errors errors !!!\n";
  602.   exit 1;
  603. }
  604.